feat: add unused_replication_slot lint for stale replication slots - #173

…ot lint

The lint's WHERE clause has no slot_type filter, so it's meant to cover both
physical and logical slots, but the test only ever exercised physical slots.
Add a negative-case fixture for a freshly created logical slot (still
wal_status='reserved' while inactive, must not fire), same guarantee as the
existing physical case. Requires wal_level=logical, which the test harness's
initdb/pg_ctl start didn't set (community Postgres default is 'replica'), so
add it to bin/installcheck's server start options.

…lication_slot lint

docs/0030_unused_replication_slot.md explicitly documents 'extended' as a
benign, must-not-fire state, but only 'reserved' was tested. Add a fixture
that shrinks max_wal_size (with max_slot_wal_keep_size left at its disabled
default, so the slot can only ever reach 'extended', never 'unreserved'/
'lost') and drives WAL past it, confirming the lint stays silent.

Per src/backend/access/transam/xlog.c's GetWALAvailability, reserved vs
extended is pure segment-count arithmetic against max_wal_size, independent
of data volume or checkpoints -- so the fixture advances WAL via repeated
pg_switch_wal() calls instead of writing real rows. pg_switch_wal() is a
no-op once already sitting at a segment boundary, so each loop iteration
emits one trivial WAL record first (pg_logical_emit_message) to move off
the boundary before switching again.

…I display

Studio's getLintEntityString (apps/studio/components/interfaces/Linter/Linter.utils.tsx)
only builds a display string when metadata.entity is set, or both
metadata.schema and metadata.name are set. This lint had name but no schema
(replication slots aren't schema-scoped) and no entity, so every finding
rendered as 'N/A' in the Advisor UI despite the slot name being known.
Setting metadata.entity to the slot name fixes this without any Studio-side
change, since the entity check short-circuits before the schema check.

…lots

pg_replication_slots.plugin names the decoding plugin (pgoutput, wal2json,
test_decoding, etc.) a logical slot uses -- null for physical slots, but
the one field that identifies which CDC tool/consumer owned an abandoned
logical slot, which the doc's remediation advice ("investigate the
disconnect") assumes a user can see.

… fixture

pg_switch_wal() forces a full segment advance regardless of preceding data
volume, and max_slot_wal_keep_size (1MB) is far below one WAL segment, so
a single trivial WAL record plus a switch already exceeds the retention
limit. The 5000-row insert added test runtime/IO for no determinism
benefit; replaced with the same lightweight emit-then-switch pattern
already used for the extended-state fixture.

…nt test

~/.claude/CLAUDE.md: a comment must be exactly one line, never a run of
several. Five explanations were spread across 2-4 consecutive -- lines;
collapsed each into one line, no content change.

~/.claude/CLAUDE.md SQL section: always schema-qualify every function
reference, never rely on search_path resolving an unqualified name. Every
other system function in this file (pg_create_physical_replication_slot,
pg_drop_replication_slot, pg_switch_wal) was already pg_catalog.-qualified;
pg_reload_conf() was the one exception.

…cation_slot

level's CASE and the WHERE clause's wal_status allowlist are two
independently-maintained expressions. Not wrong today (WHERE only ever
admits 'unreserved'/'lost', and 'unreserved' correctly falls to WARN), but
widening WHERE to admit another wal_status value without updating the CASE
would silently mislabel it WARN. One-line comment for future maintainers,
no logic change.

…ixes

bin/compile.py, reflecting the entity/plugin metadata keys and coupling
comment added to lints/0030_unused_replication_slot.sql during review.

…ments

The RESOLUTION comment on dropping a stale slot restated the action instead
of explaining why dropping is necessary. Also adds why-comments to the
WARN/ERROR case and the wal_status WHERE filter in the new
0030_unused_replication_slot lint, which previously had no rationale for why
only 'lost' escalates to ERROR and why 'reserved'/'extended' are excluded.

Both comments chained the wal_status classification and its rationale
into one long clause. Split into two short sentences on the same
line, and regenerated splinter.sql from the updated lint source.

…plication-slot-lint

* origin/main:
  ci: fail the build when the test suite fails
  feat: release splinter.json to S3
  chore: format
  fix: only release on feat/fix/breaking-change commits; defer S3 upload
  feat: generate splinter.json manifest and publish via release workflow

bin/check_lints.py (pulled in from main) requires every docs/*.md page
to have a nav entry; the new lint's page was missing one, which failed
CI's pre-commit hook.

The extended-slot fixture forces max_wal_size=2MB plus 10 WAL switches,
which triggers an async checkpoint. If that checkpoint lands after the
positive fixture's max_slot_wal_keep_size=1MB takes effect instead of
before, it invalidates the slot immediately and the 'unreserved'
assertion flakes straight to 'lost'.

Without the rationale in the file, the identical 'name'/'entity' values
in metadata read as dead duplication to a future reader; the entity key
exists only so Studio's getLintEntityString short-circuits to the slot
name instead of rendering N/A (slots have no schema).

'lost' isn't always caused by exceeding max_slot_wal_keep_size -- Postgres
16+ can also invalidate a slot for rows_removed or wal_level_insufficient,
neither of which is a WAL-retention problem. The lint's detail text and doc
both asserted the retention cause unconditionally; reword to describe the
observed wal_status rather than presuming its cause.

… own doc

'at risk of exceeding' implies the limit hasn't been hit yet, but the lint
only fires once retained WAL has already exceeded max_slot_wal_keep_size
(or the slot is already invalidated) -- the doc's own Summary and False
Positives sections already say this correctly; the description column
contradicted them.

…naged slots

The `**Level:** WARN|ERROR` header reused the skill template's pipe-separated
placeholder syntax (meaning "pick one"), but this lint is the first to
genuinely emit both depending on wal_status — on the rendered docs site that
reads as an unfilled template. State explicitly which wal_status maps to
which level instead.

Read replica provisioning and Realtime both create their own replication
slots (named after the replica's IP, or supabase_realtime_replication_slot*),
and this lint has no way to tell those apart from a user-created slot. The
remediation doc led with an unqualified "drop the slot" — for a
platform-managed slot that doesn't fix anything and can break replication or
realtime delivery outright. Add the carve-out.

Supabase's own managed Postgres always sets this GUC, but splinter also
runs against self-hosted instances. Left at Postgres's own default (-1,
never invalidate for size), an abandoned slot stays 'extended' forever and
this lint never fires -- the exact "silently eats disk" scenario the lint
exists to catch. State the dependency so a self-hosted user knows to set it.

…hecklist

0030 is the first lint whose level varies per row (a case expression,
WARN/ERROR depending on wal_status) instead of a fixed literal like every
other lint. Document it as an accepted pattern in SKILL.md's column table
and doc template, and add a check_lints.py assertion so a future dynamic-
level lint can't ship with the doc's Level line still showing the unfilled
WARN|ERROR|INFO placeholder.

CI's pre-commit black hook flagged the DYNAMIC_LEVEL_RE regex assignment as
unformatted -- black wraps it across three lines at this line length.

The regex-based DYNAMIC_LEVEL_RE check only fired for a lint with a case
expression matching one exact spelling (end as level, unquoted) and, even
then, only caught the placeholder for that one lint -- a static-level lint
left unfilled passed clean, and the regex missed realistic variants like a
quoted identifier or a cast. Drop the SQL-shape dependency entirely and
check unconditionally: no doc may contain the unfilled placeholder, for any
lint. Strictly stronger, no parsing.

Also stopped pasting instruction prose into Step 4's copy-paste fence --
an author copying it verbatim was shipping a sentence of meta-guidance
into their own doc page. The guidance now sits outside the fence; the
fence itself stays exactly what should land in the file.

supabase_realtime_replication_slot* misses Realtime's own second slot
family (supabase_realtime_messages_replication_slot_<version>_<hash>,
per platform's realtime-service stack) -- a user with an inactive slot
from that family would read the doc as permission to drop a
platform-managed slot. Widen to the supabase_realtime_* prefix platform's
own guards already use. Also spell out the ip_<x>_<x>_<x>_<x> shape
instead of leaving the reader to infer it from "named after the IP".

The test file only cleaned up at the tail, trusting a clean start -- a
prior aborted run (a failed assertion, a killed process) could leave a
stray splinter_test_* slot or a non-default GUC that turns the unrelated
file running right after it (queries_are_unionable) into a confusing
failure. Converge to a clean state at the top too: drop any stray slot,
reset both GUCs before the fixtures rely on them being at their defaults.

Documented two facts a future editor needs and wouldn't otherwise see:
the logical positive fixture depends on max_slot_wal_keep_size still
being set from the physical fixture above it, and the WAL-margin loop's
10-iteration count assumes the default 16MB wal_segment_size.

The level case expression relied on the WHERE clause (25 lines away) to
guarantee wal_status could only be 'lost' or 'unreserved', with a comment
explaining the coupling instead of the case expression enforcing it.
Made it exhaustive by listing both values explicitly instead of an else
branch, so a future widening of the WHERE clause surfaces as a null level
instead of silently mislabelling a new status as WARN.

…xture GUC state

- bin/check_lints.py: the Level-line check only rejected the exact
  unfilled placeholder string, so a doc's own docstring claim ("states
  a real level") wasn't actually enforced — a value like `TBD` or a
  typo'd level name passed clean. Now also requires the line mention
  WARN, ERROR, or INFO.
- test/sql/0030_unused_replication_slot.sql: `pg_temp.advance_wal()`
  dropped its `iterations` parameter — every call site passed the
  default, so it was unused flexibility.
- test/sql/0030_unused_replication_slot.sql: the logical positive
  fixture re-sets `max_slot_wal_keep_size` itself instead of relying on
  a comment telling editors not to reorder it away from the physical
  fixture that used to set it. test/expected output regenerated from a
  real docker pg_regress run.
- docs/0030_unused_replication_slot.md: Summary line now also covers
  the invalidated (`lost`) case, matching the Ramification/description
  wording already fixed for it.